Description

In this example, TRIDENT's digital signature API is used to confirm a transaction with a mobile device. This operation is requested by an e-bank portal (yourbank.safelayer.com) on behalf of a user (john.doe) who ordered the transfer of funds. The user logged in to the portal after authenticating in TRIDENT with their password and is accessing the website with a desktop.

The website was registered in TRIDENT (txeidas.safelayer.com) as an OAuth 2.0 client application, which means it has been associated to an authorization server (main), has an identifier (yourbank), and shares a secret with the platform (secret). The https://yourbank.safelayer.com/oauth/callback was registered as the portal's only redirect URL.

It is assumed that portal users have a mobile device (iOS or Android) with the BlueCard Mobile version of the Mobile ID application installed. We also assume that the editor of this application (BlueCard) is a certification services provider that provides a signature certificate to each user and that both this certificate and the associated signature key are stored on the user's mobile device. Lastly, we also assume that the TRIDENT platform to which yourbank accesses was provisioned with the signing identities of the users. Thus, each user has a signing identity registered in TRIDENT corresponding to the signature key they have in their device and that has the following attributes:

• The yourbank, mobile and sign labels.

• The X.509 certificate issued by BlueCard for the signature key.

• The identifier of the mobile device where the signature key is found.

The transaction is confirmed as follows:

1. User Is Authorized

2. Transaction signature request made

3. Wait for signature to be available

4. Transaction signature obtained

5. Signature process deleted

User Is Authorized

For the transaction to be signed, the user must give authorization for the portal to request the signature on their behalf. In this example, user authorization directly follows their reauthentication (i.e., it is an implicit authorization). This is established by configuration and is owing to the fact that the user will have to enter their PIN in their mobile device for the signature to be generated, which, in itself, constitutes an explicit authorization making the first one unnecessary. Furthermore, user re-authentication does not require the user's intervention as it is performed with the same authentication flow used to create the session in the portal and this flow establishes SSO for the password factor.

In any case, when the user clicks on the button for performing the transaction (Continue), the website responds with the following HTTP redirect response (see the Obtain Authorization operation):

This causes the browser to send to TRIDENT the following HTTP request specifying urn:safelayer:eidas:sign:identity:use:device as the scope of the requested authorization:

On receiving this request, TRIDENT re-authenticates the user transparently (SSO is applied) and, based on this reauthentication, it deduces that the user authorizes the website to request a signature on their behalf. Lastly, TRIDENT provides the website with the code that accredits this authorization and redirects the browser to the URL specified in the authorization request (https://yourbank.safelayer.com/oauth/callback). This redirect causes the browser to send the following HTTP request to the website:

Next, the website uses the code it receives from the browser to request the corresponding access token (see the Obtain a Token operation):

The token finally obtained in the following HTTP request:

Transaction Signature Request Made

The website builds an HTML document with the data of the transaction performed and requests that the TRIDENT prompts the user to sign the document with their mobile device. To do this, it sends the following HTTP message to the TRIDENT's signature generation service (see the Create a Transaction Signature Process with a Device operation). (For the sake of readability, an ellipsis replaces the HTML document.)

Note that the website demonstrates its authorization for requesting the signing of the transaction by including the access token (ed15...836d) in the Authorization header. Note also that the portal specifies the signing identity with which the signature must be created by including the yourbank, mobile and sign labels in the request. Therefore, as well as belonging to the john.doe user, the signing identity must correspond to a signature key on a mobile device (the mobile label), be for signing data (sign label) and have been provisioned for use in YourBank (yourbank label).

When it receives the above request, TRIDENT creates a signature process and informs the portal of the data on this process via the following HTTP response (for the sake of readability, an ellipsis replaces the JSON object containing the data on the process created):

Note that the Location header of the response contains the URL of the signature generation process created. This URL is used later for polling to detect when the signature is available.

The signature creation process starts by notifying the BlueCard Mobile application of the need to generate the signature on the transaction and to display the transaction's data to the user. If after seeing this data the user confirms the transaction, the BlueCard Mobile application prompts them to enter the PIN for the transaction signature to be generated. Lastly, the user enters their PIN and the BlueCard Mobile application generates the XAdES-EPES signature on the HTML document containing the data on the transaction and sends this signature to TRIDENT.

Wait for Signature to Be Available

Once the process for generating the transaction signature is created, the website can poll the result resource of this process. This is done by repeatedly executing the Obtain Result of the Signature Process operation until a HTTP response with the 200 status code is obtained. In this case, the transaction signature is found in the body of the response received.

The following request is repeated:

Until the following response is obtained:

Transaction Signature Obtained

Once via polling it is detected that the transaction signature has been generated, the signature is extracted from the response in which its availability was detected. Specifically, it is extracted from the value element of the JSON object in the response body (see Obtain the Result of a Signature Process). This is an XAdES-EPES signature on the HTML document containing the data on the transaction.

Signature Process Deleted

Once the transaction signature is obtained, the signature creation process used to generate the signature must be deleted. Only then can new signatures be generated with the same mobile device (i.e., with the same BlueCard Mobile instance), because until the process is deleted, all requests for generating a signature with the same device are rejected.

The signature creation process is deleted by sending the following HTTP message to the TRIDENT signature generation service (see the Delete a Signature Process operation).